package m2st.doxia.macro;

import java.io.IOException;
import java.net.URL;
import java.util.Properties;

import org.apache.maven.doxia.macro.Macro;
import org.apache.maven.doxia.macro.MacroExecutionException;
import org.apache.maven.doxia.macro.MacroRequest;
import org.apache.maven.doxia.sink.Sink;

/**
 * {@link Macro} for inserting parametrized HTML snippets
 * into the output document.
 * 
 * <p>
 * 
 * This macro works in a similar way as the {@link CodeSnippetMacro}.
 * To use this macro, you have to specify following parameters:
 * 
 * <ul>
 *  <li><tt>htmlFile</tt> or <tt>htmlUrl</tt> - HTML template location
 *  <li><tt>paramFile</tt> or <tt>paramUrl</tt> - parameter values
 *      location (content should conform to Java {@link Properties}
 *      file format)
 * </ul>
 * 
 * <p>
 * 
 * Optional macro parameters include:
 * 
 * <ul>
 *  <li><tt>id</tt> - HTML snippet identifier (can be omitted to include
 *      the entire HTML template contents)
 *  <li><tt>encoding</tt> - source file encoding (can be omitted to
 *      use <tt>UTF-8</tt> by default)
 *  <li><tt>missingValuesToEmptyStrings</tt> - if specified, missing
 *      parameter values will be replaced with empty strings in the
 *      resulting HTML code
 * </ul>
 * 
 * <p>
 * 
 * For example, HTML template
 * 
 * <pre>
 * &lt;span&gt;${my.value}&lt;/span&gt;
 * </pre>
 * 
 * together with parameter values
 * 
 * <pre>
 * my.value=Hello!
 * </pre>
 * 
 * results in the inclusion of
 * 
 * <pre>
 * &lt;span&gt;Hello!&lt;/span&gt;
 * </pre>
 * 
 * into the output document.
 * 
 * @see BaseMacro
 * 
 * @author vojtech.szocs
 * 
 * @plexus.component role="org.apache.maven.doxia.macro.Macro" role-hint="html-template-snippet"
 */
public class HtmlTemplateSnippetMacro extends BaseMacro {

    /**
     * @see org.apache.maven.doxia.macro.Macro#execute(org.apache.maven.doxia.sink.Sink, org.apache.maven.doxia.macro.MacroRequest)
     */
    public void execute(Sink sink, MacroRequest request) throws MacroExecutionException {
        URL htmlUrl = getResourceUrl(request, "htmlUrl", "htmlFile");
        URL paramUrl = getResourceUrl(request, "paramUrl", "paramFile");
        
        String id = (String) request.getParameter("id");
        String encoding = (String) request.getParameter("encoding");
        Object missingValuesToEmptyStrings = request.getParameter("missingValuesToEmptyStrings");
        
        if (encoding == null)
            encoding = DEFAULT_ENCODING;
        
        HtmlTemplateSnippet snippet;
        
        try {
            snippet = new HtmlTemplateSnippet(id, htmlUrl, paramUrl, encoding, missingValuesToEmptyStrings != null);
        } catch (IOException e) {
            throw new MacroExecutionException("Error while processing HTML snippet with template URL " + htmlUrl + " and parameter values URL " + paramUrl, e); 
        }
        
        sink.rawText(snippet.toString());
    }
    
}
